“Creating Made Simple.”
Composer is a simple but powerful CMS based on Pandoc and Make. By default, input files are written in a variation of Markdown.
Traditionally, CMS stands for Content Management System. In the case of Composer, however, CMS really means a Content Make System. For many types of content, maybe even most, simpler is better. Content is very easy to manage when it lives its full life-cycle as plain text, since there are a veritable multitude of solutions available for tracking and managing text and source files. What is really needed is a basic system with advanced capabilities for “making” these simple text files into richer, more capable document types.
This is the goal of Composer.
Composer is completely self-documenting. To get the full usage and help output:
make helpTo download/update some necessary 3rd party components:
make updateTo build an example/test directory using all features:
make testIn the simplest case, Composer can be used to make the conversion of Markdown files to other formats a trivial task. The real strength and goal of Composer, however, is as a recursive build system for any type of output content (websites, manuals/documentation, etc.).
Composer is really nothing more than a Make-based wrapper to Pandoc. The author started out with the following requirements for an all-purpose documentation production system:
While support for a multitude of output formats was desired, the following were absolute necessities:
A thorough review and test of the large number of available input formats and formatting engines resulted in a very short list of projects which could support the above requirements. Pandoc was selected for a number of reasons:
Pandoc provided the perfect engine, but running long strings of commands was not feasible for quick and simple command-line use, and the thought of writing new scripting/automation each time a large-scale project emerged was not terribly exciting. Thus, Make was selected as a wrapping engine based on it’s years of history as one of the most popular and highly used source file processing systems in use.
The final result is Composer, which leverages these two tools to accomplish the original goals with a minimum amount of user knowledge and expertise, and to provide a solid foundation for simplified management of larger content production efforts.
Composer is developed and tested on a Funtoo/Gentoo GNU/Linux system. An effort has been made to do things in a portable way, but cross-platform development is not an area of expertise for the author.
Output of make --version on development system:
GNU Make 3.82
Built for x86_64-pc-linux-gnu
Output of pandoc --version on development system:
pandoc 1.12.3.3
Compiled with texmath 0.6.6, highlighting-kate 0.5.6.1.
If you discover issues, please contact the author directly, with advance thanks. It is highly desirable for Composer to be as “run anywhere” as possible.
Running the commands in the Quick Start section will help you validate whether your system will work as expected. In particular, the make test command validates the proper functioning of all the supported features and uses of Composer.
Composer is not really revisioned into “releases” outside of the source code repository. Each commit is tested using make test first, so the latest source should always be ready for production.
If you require greater assurance of stability, use a version of the source that is tagged with a version number.
Composer was designed to have a minimum of external dependencies:
In order to download/update the 3rd party components, such as style sheets and formatters, these are also needed:
Components from these 3rd party projects are used:
Basically, any GNU-based system, such as GNU/Linux, Cygwin or FreeBSD (with the GNU tools installed), should work just fine. The biggest external dependency is Pandoc itself and the LaTeX system it uses to produce some of the output formats (namely PDF).
There are a couple important items to be aware of when using Composer:
$(COMPOSER_ABSPATH) variable may be overly-clever and therefore not portable.$(COMPOSER_DEPENDS) variable as documented.override OPTS := instead of override OPTS ?=) and place them below the upstream include statements.make help, is tested and supported, and does not require any modifications to the main Make file.export command should not be used in any Make files read by Composer, other than the provided examples in make help which have been tested.make help output could be much more kind to those not working on huge terminal windows.Finally, it could be that Composer introduces more complexity than it does add value, which this author guesses is likely true for many.
The author encourages the reader to review the Goals section and decide for themselves if Composer will be beneficial for their needs.